\documentclass[12pt]{article}
\usepackage{fullpage}
\usepackage{palatcm}
\def\smtxcmd#1{\subsubsection*{{\tt #1}}}
\title{The Smash MeatAxe for {\sf GAP4}}
\author{Alexander Hulpke}
\date{November 19, 1996}
\def\SMTX{{\sf SMTX}}
\begin{document}
\maketitle
The {\sf Smash}-MeatAxe {\SMTX} is a modification of the MeatAxe in the {\sf
Smash} share library, originally written by Derek Holt and Sarah Rees. It is
adapted to {\sf GAP4}
(where it is intended to become the standard library MeatAxe
unless someone else is willing to write a better one) and works according to
the standardized MeatAxe interface. This document describes the implemented
features as well as some internal routines that resemble features of the
old {\sf Smash}-MeatAxe.\\
If you feel that routines for certain functions are missing {\em please ask
me before writing them yourself. There might be some internal feature that
allows easy addition already available!}\\
The routines will only work if the module given is a full row vector space.\\
The routines from {\SMTX} are selected by setting {\verb+ MTX:=SMTX;+}.

\section*{Commands}
\smtxcmd{SMTX.SubQuotActions(matrices,sub,dim,subdim,one,type)}
is the working horse of the basic chopping routines: {\tt matrices} is a
list of matrices in dimension {\tt dim}, {\tt sub} is the basis of a
subspace in dimension {\tt subdim}. The respective one is given by {\tt
one}. The integer {\tt type} finally encodes in its binary decomposition
which actions are to be performed: 1 stands for subspace action, 2 for
factor action and 4 for action of the full module
on a subspace adapted basis. The routine
returns a record with components (if applicable): {\tt smatrices}, {\tt
qmatrices} and {\tt nmatrices} giving new matrices for the three possible
actions and {\tt nbasis} an extension of the basis given in {\tt sub} with
respect to which the action is performed.\\
The routine returns {\tt fail} if {\tt sub} is not a proper subspace.\\
The basis given in {\tt sub} must be normed!\\
There are a couple of further routines that basically just call
SubQuotActions to provide several layers of interfacing (and also return
{\tt fail} if {\tt sub} is not a submodule basis):

\smtxcmd{SMTX.InducedAction(module,sub[,type])}
just calls {\tt SubQuotActions}, but returns module actions instead of
matrices and returns the computed results in a list in sequence
(sub,quot,both,basis) instead of record components. If no {\tt type} is
given, it is assumed to be 7.\\
The basis given in {\tt sub} must be normed!

\smtxcmd{SMTX.SubGModuleAction(sub,matrices)}
computes matrices for just the subspace action. SCHEDULED FOR ELIMINATION!

\smtxcmd{SMTX.InducedActionSubmodule(module,sub)}
creates a new module corresponding to the action of {\tt module} on {\tt sub}.

\smtxcmd{SMTX.InducedActionSubmoduleNB(module,sub)}
Dito, but the basis in {\tt sub} must be normed.

\smtxcmd{SMTX.InducedActionFactorModule(module,sub[,compl])}
creates a new module corresponding to the action of {\tt module} on the
factor of {\tt sub}. If {\tt compl} is given, it has to be a basis of a
(vectorspace-)complement of {\tt sub}. The action then will correspond to
{\tt compl}.

\smtxcmd{SMTX.ProperSubmoduleBasis(module)}
returns the action on a proper submodule and {\tt fail} if none exists.

\smtxcmd{SMTX.SMCoRaEl(matrices,ngens,newgenlist,dim,F)}
internally used to create a random element
PROBABLY NOT AN END-USER FUNCTION. JUST LISTED AS PARTS OF SMASH MIGHT STILL
CONTAINED DUPLICATE CODE PUT HEREIN.

\smtxcmd{SMTX.IrreducibilityTest(module)}
Tests for irreducibility and sets a subbasis if reducible. It neither sets
an irreducibility flag, nor tests it. Thus the routine also can simply be
called to obtain a random submodule.

\smtxcmd{SMTX.IsIrreducible(module)}
if necessary calls the irreducibility test and sets a flag to be returned
otherwise. The existence of the flag can be checked with 
{\tt SMTX.HasIsIrreducible}

\smtxcmd{SMTX.AbsoluteIrreducibilityTest(module)}
Tests for absolute irreducibility and sets splitting field degree. It
neither sets an absolute irreducibility flag, nor tests it.

\smtxcmd{SMTX.IsAbsolutelyIrreducible(module)}
if necessary calls the absolute irreducibility test and sets a flag to be
returned otherwise. The existence of the flag can be checked with 
{\tt SMTX.HasIsAbsolutelyIrreducible}

\smtxcmd{SMTX.RandomIrreducibleSubGModule(module)}
returns the module action on a random irreducible submodule.

\smtxcmd{SMTX.GoodElementGModule(module)}
finds an element with minimal possible nullspace dimension if {\tt module}
is known to be irreducible

\smtxcmd{SMTX.CompleteBasis(module,pbasis)}
extends {\tt pbasis} to a basis of the full space by action of {\tt module}.
It returns whether it succeeded.

\smtxcmd{SMTX.DegreeFieldExt(module)}
returns the degree of the splitting field extension.

\smtxcmd{SMTX.DegreeSplittingField(module)}
returns the degree of the splitting field extension over the prime field

\smtxcmd{SMTX.CollectedFactors(module)}
returns a list giving all irreducible composition factors with their
frequencies.

\smtxcmd{SMTX.CompositionFactors(module)}
returns a list of composition factors in ascending order

\smtxcmd{SMTX.Distinguish(cf,nr)}
Let {\tt cf} be the output of {\tt SMTX.CollectedFactors}. This routine
tries to find a group algebra element that has nullity zero on all
composition factors except {\tt nr}.

\smtxcmd{SMTX.MinimalSubGModule(module,cf,nr)}
returns the basis of a minimal submodule of {\tt module} containing the
indicated composition factor. It assumes {\tt Distinguish} has been called
already

\smtxcmd{SMTX.Isomorphism(module1,module2)}
returns an isomorphism from module1 to module2 (if any exists) and {\tt
fail} otherwise. It needs that one of the modules is known to be
ireducible. It implicitly assumes that the same group is acting, otherwise
the results are unpredictable.
The isomorphism is given by a matrix $M$, whose rows give the images of the
standard basis vectors of module2 in the standard basis of module1. That is,
conjugation of the generators of {\tt module2} with $M$ yields the
generators of {\tt module1}.

\smtxcmd{SMTX.IsEquivalent(module1,module2)}
tests two irreducible modules for equivalence.

\smtxcmd{SMTX.MatrixSum(matrices1,matrices2)}
creates the direct sum of two matrix lists

\smtxcmd{SMTX.Homomorphisms(module1,module2)}
returns a basis of all homomorphisms from the irreducible module {\tt
module1} to {\tt module2}.

\smtxcmd{SMTX.SortHomGModule(module1,module2,homs)}
Function to sort the output of {\tt Homomorphisms}

\smtxcmd{SMTX.MinimalSubGModules(module1,module2[,max])}
returns (at most {\tt max}) bases of submodules of module2 which are
isomorphic to the irreducible {\tt module1}.

\smtxcmd{SMTX.BasesCompositionSeries(module)}
returns a list of bases of submodules in a composition series in ascending
order

\smtxcmd{SMTX.BasesMinimalSubmodules(module)}
returns a list of bases of all minimal submodules

\smtxcmd{SMTX.BasesMaximalSubmodules(module)}
returns a list of bases of all maximal submodules

\smtxcmd{SMTX.BasesMinimalSupermodules(module,sub)}
returns a list of bases of all minimal supermodules of the submodule given by
the basis {\tt sub}.

\smtxcmd{SMTX.BasesSubmodules(module)}
returns a list containing a basis for every submodule

\smtxcmd{SMTX.Setter(string)}
returns a setter function for the component {\tt smashMeataxe.(string)}.

\smtxcmd{SMTX.Getter(string)}
returns a getter function for the component {\tt smashMeataxe.(string)}.

\subsection*{Flags}

The following getter routines access internal flags. For each routine, the
appropriate setters name is prefixed with {\tt Set}.

\smtxcmd{SMTX.Subbasis}
Basis of a submodule

\smtxcmd{SMTX.AlgEl}
list {\tt[newgens,coefflist]} giving an algrebra element used for chopping

\smtxcmd{SMTX.AlgElMat}
matrix thereof

\smtxcmd{SMTX.AlgElCharPol}
minimal polynomial thereof

\smtxcmd{SMTX.AlgElCharPolFac}
used factor thereof

\smtxcmd{SMTX.AlgElNullspaceVec}
nullspace of the matrix evaluated under this factor

\smtxcmd{SMTX.AlgElNullspaceDimension}
dimension thereof

\smtxcmd{SMTX.CentMat}

\smtxcmd{SMTX.CentMatMinPoly}

\newpage

\section*{Translation of old names}
\begin{tabular}{ll}
Old&New\\
\hline
ChopGMod&SMTX.CollectedFactors\\
CompleteBasis&SMTX.CompleteBasis\\
Distinguish&SMTX.Distinguish\\
EnlargeIrreducibleGModule&${}^\dag$\\
FieldGenCentMat&${}^\dag$\\
FrobAction&SMTX.FrobeniusAction\\
GoodElMod&SMTX.GoodElementGModule\\
HomGMod&SMTX.Homomorphisms\\
IsAbsIrredGMod&SMTX.AbsoluteIrreducibilityTest${}^\dag$\\
&SMTX.IsAbsolutelyIrreducible${}^\dag$\\
IsIrredGMod&SMTX.IrreducibilityTest${}^\dag$\\
&SMTX.IsIrreducible${}^\dag$\\
IsomGMod&SMTX.Isomorphism(module1,module2)\\
MatSum&SMTX.MatrixSum\\
MinSub&SMTX.MinimalSubGModule\\
MinSubGMods&SMTX.MinimalSubGModules\\
OrthogVec&SMTX.OrthogonalVector\\
QuotGMod&SMTX.InducedActionFactorModule\\
RandomIrredSubGMod&SMTX.RandomIrreducibleSubGModule\\
SetAlgElCharPolFacFlag&SMTX.SetAlgElCharPolFac\\
SetAlgElCharPolFlag&SMTX.SetAlgElCharPol\\
SetAlgElFlag&SMTX.SetAlgEl\\
SetAlgElMatFlag&SMTX.SetAlgElMat\\
SetAlgElNullspaceDimFlag&SMTX.SetAlgElNullspaceDimension\\
SetAlgElNullspaceVecFlag&SMTX.SetAlgElNullspaceVec\\
SetCentMatFlag&SMTX.SetCentMat\\
SetCentMatMinPolyFlag&SMTX.SetCentMatMinPoly\\
SetSubbasisFlag&SMTX.SetSubbasis\\
SortHomGMod&SMTX.SortHomGModule\\
SpinBasis&SMTX.SpinnedBasis\\
SubGMod&SMTX.InducedActionSubmodule\\
SubGModAction&SMTX.SubGModuleAction\\
SubQuotGMod&SMTX.InducedAction\\
\end{tabular}\\
All functions return {\tt fail} to indicate impossibility to perform instead
of {\tt false}.\\
\dag indicates that the performed functions were slightly changed.
\end{document}
